Copilot supported conversion to SCSS Modules by andrewscfc · Pull Request #13013 · bbc/simorgh

andrewscfc · 2025-07-25T12:15:14Z

Summary

This PR presents a viable alternative to Emotion for styling; in a retro in the summer we identified that Emotion presents several pain points and currently blocks the adoption of App Router in NextJS.

The PR presents an approach utilising SASS, CSS Modules and CSS custom variables; the high level approach is as follows:

We create a ThemeProviderSCSSModules that imports relevant fonts and styles dependent on the chosen service, as the ThemeProvider does today
This wraps the existing page like the existing ThemeProvider does
The ThemeProviderSCSSModules imports css modules that declare suitable css custom variables that are dictated by the chosen service
These variables are used in module SCSS files in components to interface with the customisations the service's theme makes
- Curation/Subhead is implemented as an example utilising ths new theme system with SCSS\
- ArticlesLinksBlock is a bigger component implemented with the new theme system.
The variables can be interfaced with via SCSS mixins; an example can be found here where we take the chosen font scale and assign font-size and line-height as controlled by the css custom variables configured by the theme.

Tech Choice Rationale

CSS modules allows a direct conversion of emotion styles to css module files, you are ultimately expressing raw css as you do with emotion, conversions can be reviewed with confidence.
- Adoption of a technology such as tailwind would need the reviewer to understand tailwind and translate the converted css to that tech's best practices and features
SCSS and CSS custom variables allow us to replicate the Emotion theming as we have it today replicating existing theme configuration

Adoption path

The approach 'as-is' can co-exist with Emotion styling so could be adopted gradually
I would really like to automate migration via extensive use of AI tools

Limitations

Works in Next app and Storybook
Partially works in Express, you can uncomment here to play with it in Express but doesn't seem a priority)
Only Mundo theme implemented

Next Steps

Get buy in from development team to new approach
Implement remaining service themes (mundo was done with Copilot support, the other themes should be doable with similar automation - here is a pretty good attempt I did with AI on a learning day Scss modules remaining themes implemented with AI #13845)
Merge PR with MVP solution styling Curation/Subhead + ArticleLinksBlock only

Useful Links

Coding Standards
Repository use guidelines
Add Links to useful resources related to this PR if applicable.

andrewscfc · 2025-07-25T12:16:39Z

    "puppeteer": "24.10.2",
    "retry": "0.13.1",
+    "sass": "1.89.2",
+    "sass-loader": "16.0.5",


copilot recommended packages to support SCSS

andrewscfc · 2025-07-25T12:36:10Z

@@ -0,0 +1,223 @@
+// fontFaces.module.scss
+// SCSS mixins for @font-face rules, matching the fontFaces.ts constants
+// Usage: @include reith-serif-regular-face; etc.


seems a pretty direct conversion from the ts constants: https://github.com/bbc/simorgh/blob/latest/src/app/components/ThemeProvider/fontFaces.ts

andrewscfc · 2025-07-25T12:40:10Z

@@ -0,0 +1,22 @@
+// fontFamilies.module.scss
+// SCSS variables for font-family stacks, matching fontFamilies.ts
+// Usage: font-family: $reith-sans;


Original file: https://github.com/bbc/simorgh/blob/latest/src/app/components/ThemeProvider/fontFamilies.ts

andrewscfc · 2025-07-25T12:46:29Z

@@ -0,0 +1,14 @@
+// fontMediaQueries.module.scss
+// SCSS variables for font media query breakpoints, matching fontMediaQueries.ts
+// These are static values representing only the media query condition (no @media, no quotes).


After some back and forth with Copilot it told me that you can't have constants that contain full media queries like the original file

You can get very close though with the condition being encapsulating in a variable

andrewscfc · 2025-07-25T12:49:56Z

+  $values: map-get(map-get($font-sizes, $scale), $group);
+  font-size: map-get($values, font-size);
+  line-height: map-get($values, line-height);
+}


This was a really difficult conversion, the theme dictates the font size and line height so it seemed sensible for these be declared as global variables to set at runtime by JS based on the service theme. In theory the algorithm otherwise works the same as the ts version: https://github.com/bbc/simorgh/blob/latest/src/app/components/ThemeProvider/fontSizes.ts

andrewscfc · 2025-07-25T12:50:29Z

+$storm: #404040;
+$success-core: #148A00;
+$weather-blue: #067EB3;
+$white: #FFFFFF;


original file: https://github.com/bbc/simorgh/blob/latest/src/app/components/ThemeProvider/palette.ts

andrewscfc · 2025-07-25T12:52:13Z

+$margin-below-400px: $full;
+$gutter-below-600px: $full;
+$margin-above-400px: $double;
+$gutter-above-600px: $double;


Quite a good comparison to the just CSS Modules equivalent, pretty much all the imperative logic is retained from the original: https://github.com/bbc/simorgh/blob/latest/src/app/components/ThemeProvider/spacings.ts

andrewscfc · 2025-07-30T15:02:26Z

+    'brand-logo': 'var(--white)',
+    'brand-foreground': 'var(--ghost)',
+    'brand-highlight': 'var(--white)',
+    'brand-border': 'var(--postbox-30)',


First example pulling in custom properties dynamically based on theme, this should reflect current behaviour

…ilot]

andrewscfc · 2025-08-01T15:32:43Z

    "jest-serializer-html": "7.1.0",
    "jest-silent-reporter": "0.6.0",
    "jsdom": "26.1.0",
+    "mini-css-extract-plugin": "2.9.2",


Copilot claims this enables extraction of css into seperate chunks based on usage

andrewscfc · 2025-08-01T15:36:54Z

+  $ratio: if($cropped-height != 0, $cropped-width / $cropped-height, 1);
+
+  :root {
+    --brand-logo-ratio: #{$ratio};


It's a bit of a stretch but in principle this algorithm will set this custom css property to refer to when putting the css together for the brand here:

simorgh/src/app/legacy/containers/Brand/index.jsx

Line 40 in 140e62c

const svgRatio = brandSVG && brandSVG.ratio;

andrewscfc · 2025-08-01T15:39:26Z

@@ -0,0 +1,30 @@
+@mixin build-logo(


This meant to be roughly functional equivalent to: https://github.com/bbc/simorgh/blob/latest/src/app/components/ThemeProvider/chameleonLogos/index.tsx#L5

it compute values to use elsewhere for the brand and provides a suitable css class to use for styles

andrewscfc · 2025-08-01T15:40:09Z

+  stroke: #000;
+  stroke-width: 0.335;
+  /* Optionally, set stroke via custom property or theme */
+}


I think this needs moving to the :root declaration above to make it global for use elsewhere

andrewscfc · 2025-08-01T15:41:48Z

+
+.mundoLogoTheme {
+  @include logo.build-logo(1738, 425);
+}


Applies mundo specific config to logo and actually executes the function, adding the suitably populated custom properties to the page

Based on: https://github.com/bbc/simorgh/blob/latest/src/app/components/ThemeProvider/chameleonLogos/mundo.tsx#L4

andrewscfc · 2025-08-01T15:55:15Z

+import '../../../fontVariants/reith.module.scss';
+import './palette.module.scss';
+import '../../../fontScripts/latinWithDiacritics.module.scss';
+import '../../../chameleonLogos/mundoLogo.module.scss';


Quite important implementation detail here, these scss modules are imported and applied to the page, but because this is dynamically imported via loadable the theory is this css is correctly chunked with mundo only i.e. only css for the chosen theme is loaded

andrewscfc · 2025-08-01T15:57:39Z

+:root {
+  --brand-background: var(--postbox);
+  --brand-logo: var(--white);
+  --brand-foreground: var(--ghost);
+  --brand-highlight: var(--white);
+  --brand-border: var(--postbox-30);
+}


Suggested change

:root {

--brand-background: var(--postbox);

--brand-logo: var(--white);

--brand-foreground: var(--ghost);

--brand-highlight: var(--white);

--brand-border: var(--postbox-30);

}

This file was moved, should be deleted

andrewscfc · 2025-08-01T15:57:50Z

+:root {
+  --brand-background: var(--postbox);
+  --brand-logo: var(--white);
+  --brand-foreground: var(--ghost);
+  --brand-highlight: var(--white);
+  --brand-border: var(--postbox-30);
+}


Equivalent of:

simorgh/src/app/components/ThemeProvider/themes/mundo.ts

Line 14 in 140e62c

palette: {

andrewscfc · 2025-08-01T15:58:43Z

+};
+
+
+export default ThemeProvider;


Equivalent of

simorgh/src/app/components/ThemeProvider/withThemeProvider.tsx

Line 44 in 140e62c

const withThemeProvider = (

This is simplified for now and obviously creates its own Provider rather than use emotion

andrewscfc · 2025-09-05T13:09:22Z

+  };
+};
+
+export default buildLogo;


Existing logic for brand svg unchanged by move to SCSS modules

andrewscfc · 2025-09-05T13:34:32Z

+import '../../../fontFaces/reith-serif-light.module.scss';
+import '../../../fontVariants/reith.module.scss';
+import './palette.module.scss';
+import '../../../fontScripts/latinWithDiacritics.module.scss';


Quite important implementation detail here, these scss modules are imported and applied to the page, but because this is dynamically imported via loadable the theory is this css is correctly chunked with mundo only i.e. only css for the chosen theme is loaded

andrewscfc · 2025-09-05T13:39:18Z

+import '../../fontFaces/reith-serif-light.module.scss';
+import '../../fontVariants/reith.module.scss';
+import './palette.module.scss';
+import '../../fontScripts/latinWithDiacritics.module.scss';


Quite important implementation detail here, these scss modules are imported and applied to the page, but because this is dynamically imported via loadable the theory is this css is correctly chunked with mundo only i.e. only css for the chosen theme is loaded

andrewscfc · 2025-09-05T16:15:32Z

+.h2 {
+  font-family: var(--sans-bold-font-family);
+  font-style: var(--sans-bold-font-style);
+  font-weight: var(--sans-bold-font-weight);


Font values are set from those applied here: https://github.com/bbc/simorgh/pull/13013/files#diff-606b2cf1ad95cb660e27b11c09db812ce4f721759062e7cb05c0488e8e892f01R5

This usage font variables should be abstracted by a mixin, todo

Co-authored-by: Andrew Bennett <andrew.bennett07@bbc.co.uk>

andrewscfc · 2026-03-19T09:41:37Z

+import '../../fontFaces/reith-serif-light.scss';
+import '../../fontVariants/reith.scss';
+import './palette.scss';
+import '../../fontScripts/latinWithDiacritics.scss';


These imports all have side-effects, defining various css global variables specific to the theme. These are used to alter styles by theme dynamically at runtime.

A quite crucial bit of config was needed here to allow these side effects to take effect.

andrewscfc · 2026-03-19T09:44:50Z

+  mundo: loadable(
+    () => import(/* webpackChunkName: "themes-mundo" */ './mundo/mundo'),
+  ),
+};


The same dynamic import approach is utilised for themes; this allows only the relevant assets to be requested as before.

andrewscfc · 2026-03-19T09:48:17Z

+$group-3-max-width-bp: 62.9375; // 1007px / 16
+$group-4-min-width-bp: 63; // 1008px / 16
+$group-4-max-width-bp: 79.9375; // 1279px / 16
+$group-5-min-width-bp: 80; // 1280px / 16


Should be changed to use this utility for better readability to mirror the original https://github.com/bbc/simorgh/pull/13013/changes#diff-540a8d34d9211a4ca979d5eaef6394b41db38f899063a5519636507f5a9b0113R3

andrewscfc · 2026-03-19T09:49:30Z

+$triple: $full * 3; // 1.5rem (24px)
+$quadruple: $full * 4; // 2rem (32px)
+$quintuple: $full * 5; // 2.5rem (40px)
+$sextuple: $full * 6; // 3rem (48px)


Should be changed to use this utility for better readability to mirror the original https://github.com/bbc/simorgh/pull/13013/changes#diff-540a8d34d9211a4ca979d5eaef6394b41db38f899063a5519636507f5a9b0113R3

andrewscfc · 2026-03-19T09:51:30Z

-                        {RenderChildrenOrError}
-                      </PageWrapper>
-                    </ThemeProvider>
+                    <ThemeProviderSCSSModules service="mundo">


hardcode to mundo for now

andrewscfc · 2026-03-19T10:22:13Z

+                modules: true,
+                importLoaders: 1,
+                esModule: false,
+              },


This config was very trial and error to achieve, copilot suggests that:

modules: true is enabled to support css modules

importLoaders: 1 ensures files imported in css modules go through the sass loader first

esModule: false is needed for compatibility with style loader

This may be an area to optimise but with Express going soon it isn't a major area of concern

andrewscfc · 2026-03-19T10:23:50Z

+          use: ['css-loader', 'sass-loader'],
+        },
+      ],
+    },


same config as client except style-loader/MiniCssExtractPlugin is not needed as the css is not being inserted into pages on the server

…rew-scss-modules

…ontVariants/index.tsx [copilot]

andrewscfc commented Jul 25, 2025

View reviewed changes

andrewscfc added the Copilot label Jul 25, 2025

andrewscfc commented Jul 30, 2025

View reviewed changes

andrewscfc force-pushed the andrew-scss-modules branch from c3a0d1d to 8821093 Compare August 1, 2025 14:22

andrewscfc added 7 commits August 1, 2025 15:26

copilot driven introduction of SCSS Modules [copilot]

47e9bb1

guided copilot conversion of styling constants/utilities to SCSS [cop…

1f6a4d4

…ilot]

beginning of theme application with SCSS [copilot]

82b3c26

support code splitting for css modules [copilot]

8db0a50

mundo font nearly entirely converted to scss modules [copilot]

ed3da93

mundo theme has brand logo converted to SCSS modules [copilot]

719c18f

first attempt at full theme setup with scss modules [copilot]

0a8dcd6

andrewscfc force-pushed the andrew-scss-modules branch from 8821093 to 0a8dcd6 Compare August 1, 2025 14:27

Merge branch 'latest' of github.com:bbc/simorgh into andrew-scss-modules

c067875

andrewscfc commented Aug 1, 2025

View reviewed changes

andrewscfc added 5 commits September 4, 2025 08:56

Merge branch 'latest' into andrew-scss-modules

c395ea7

Merge branch 'latest' into andrew-scss-modules

d49af8a

Delete fontFacesLazy.module.scss as mixins only work at build time

622f783

Delete moved palette/mundo.module.scss

b0c19da

keep original brand svg solution as it is unaffected by SCSS modules

0df1134

andrewscfc commented Sep 5, 2025

View reviewed changes

Remove import of removed scss module

45fc3cf

andrewscfc commented Sep 5, 2025

View reviewed changes

correct imports

9fa6533

andrewscfc commented Sep 5, 2025

View reviewed changes

andrewscfc added 3 commits September 5, 2025 16:32

Curation container except fonts [copilot]

14e8656

font parameters converted to reference theme variables

65e904f

first fully converted component scss module [copilot]

a5a4f48

andrewscfc force-pushed the andrew-scss-modules branch from 403d74b to a5a4f48 Compare September 5, 2025 16:08

Merge branch 'latest' into andrew-scss-modules

b990200

andrewscfc commented Sep 5, 2025

View reviewed changes

remove comments

19648c4

Co-authored-by: Andrew Bennett <andrew.bennett07@bbc.co.uk>

andrewscfc commented Mar 19, 2026

View reviewed changes

andrewscfc added 4 commits March 19, 2026 10:44

Merge branch 'latest' of github.com:bbc/simorgh into andrew-scss-modules

80158c7

yarn install after merge

b9bd6da

Merge branch 'andrew-scss-modules' of github.com:bbc/simorgh into and…

935a243

…rew-scss-modules

fix express partially working for demonstration purposes [copilot]

5e0d3f2

andrewscfc changed the title ~~Copilot guided conversion to SCSS Modules~~ Copilot supported conversion to SCSS Modules Mar 19, 2026

andrewscfc added 17 commits March 19, 2026 16:55

introduce basic mix-in for fontVariant [copilot]

0ad1d28

Full fontVariant mixin replicating src/app/components/ThemeProvider/f…

2879b6d

…ontVariants/index.tsx [copilot]

Merge branch 'latest' of github.com:bbc/simorgh into andrew-scss-modules

f28ed32

Merge branch 'latest' into andrew-scss-modules

25a81fb

use px-to-rem utility more widely to aid readability [copilot]

f34f953

Convert ArticleLinksBlock to scss + fix gaps in theming [copilot]

f0bc46f

Merge branch 'latest' of github.com:bbc/simorgh into andrew-scss-modules

f162b1c

fix incorrectly suffixed rem values [copilot]

10fc835

re-apply rem suffixes to media query [copilot]

5c07a16

introduce px-to-rem utility to medaQueries and adjust usage [copilot]

cec63db

Merge branch 'latest' into andrew-scss-modules

6ffd94c

introduce centralised type for scss modules [copilot]

b8a808f

simplify theme import syntax [copilot]

72fbe34

fix tests following theming path being introduced [copilot]

6890039

Merge branch 'latest' into andrew-scss-modules

4e9ec7b

move to webpack alias based approach [copilot]

dca80c6

Merge branch 'latest' into andrew-scss-modules

5f028bd

		};


		export default ThemeProvider; No newline at end of file

Conversation

andrewscfc commented Jul 25, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Summary

Tech Choice Rationale

Adoption path

Limitations

Next Steps

Useful Links

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

andrewscfc Jul 30, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

andrewscfc Mar 19, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

andrewscfc Mar 19, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

andrewscfc commented Jul 25, 2025 •

edited

Loading

andrewscfc Jul 30, 2025 •

edited

Loading

andrewscfc Mar 19, 2026 •

edited

Loading

andrewscfc Mar 19, 2026 •

edited

Loading